28.1.6 Examining And Comparing Old Revisions

C-x v =

Compare the work files in the current VC fileset with the versions you started from (vc-diff). With a prefix argument, prompt for two revisions of the current VC fileset and compare them. You can also call this command from a Dired buffer (see Dired).

M-x vc-ediff

Like C-x v =, but using Ediff. See Ediff in The Ediff Manual.

C-x v D

Compare the entire working tree to the revision you started from (vc-root-diff). With a prefix argument, prompt for two revisions and compare their trees.

C-x v ~

Prompt for a revision of the current file, and visit it in a separate buffer (vc-revision-other-window).

C-x v g

Display an annotated version of the current file: for each line, show the latest revision in which it was modified (vc-annotate).

C-x v = (vc-diff) displays a diff which compares each work file in the current VC fileset to the version(s) from which you started editing. The diff is displayed in another window, in a Diff mode buffer (see Diff Mode) named *vc-diff*. The usual Diff mode commands are available in this buffer. In particular, the g (revert-buffer) command performs the file comparison again, generating a new diff.

To compare two arbitrary revisions of the current VC fileset, call vc-diff with a prefix argument: C-u C-x v =. This prompts for two revision IDs (see VCS Concepts), and displays a diff between those versions of the fileset. This will not work reliably for multi-file VC filesets, if the version control system is file-based rather than changeset-based (e.g., CVS), since then revision IDs for different files would not be related in any meaningful way.

Instead of the revision ID, some version control systems let you specify revisions in other formats. For instance, under Bazaar you can enter ‘date:yesterday’ for the argument to C-u C-x v = (and related commands) to specify the first revision committed after yesterday. See the documentation of the version control system for details.

If you invoke C-x v = or C-u C-x v = from a Dired buffer (see Dired), the file listed on the current line is treated as the current VC fileset.

M-x vc-ediff works like C-x v =, except that it uses an Ediff session. See Ediff in The Ediff Manual.

C-x v D (vc-root-diff) is similar to C-x v =, but it displays the changes in the entire current working tree (i.e., the working tree containing the current VC fileset). If you invoke this command from a Dired buffer, it applies to the working tree containing the directory.

You can customize the diff options that C-x v = and C-x v D use for generating diffs. The options used are taken from the first non-nil value amongst the variables vc-backend-diff-switches, vc-diff-switches, and diff-switches (see Comparing Files), in that order. Here, backend stands for the relevant version control system, e.g., bzr for Bazaar. Since nil means to check the next variable in the sequence, either of the first two may use the value t to mean no switches at all. Most of the vc-backend-diff-switches variables default to nil, but some default to t; these are for version control systems whose diff implementations do not accept common diff options, such as Subversion.

To directly examine an older version of a file, visit the work file and type C-x v ~ revision RET (vc-revision-other-window). This retrieves the file version corresponding to revision, saves it to filename.~revision~, and visits it in a separate window.

Many version control systems allow you to view files annotated with per-line revision information, by typing C-x v g (vc-annotate). This creates a new “annotate” buffer displaying the file’s text, with each line colored to show how old it is. Red text is new, blue is old, and intermediate colors indicate intermediate ages. By default, the color is scaled over the full range of ages, such that the oldest changes are blue, and the newest changes are red. If the variable vc-annotate-background-mode is non-nil, the colors expressing the age of each line are applied to the background color, leaving the foreground at its default color.

When you give a prefix argument to this command, Emacs reads two arguments using the minibuffer: the revision to display and annotate (instead of the current file contents), and the time span in days the color range should cover.

From the “annotate” buffer, these and other color scaling options are available from the ‘VC-Annotate’ menu. In this buffer, you can also use the following keys to browse the annotations of past revisions, view diffs, or view log entries:

p

Annotate the previous revision, i.e., the revision before the one currently annotated. A numeric prefix argument is a repeat count, so C-u 10 p would take you back 10 revisions.

n

Annotate the next revision, i.e., the revision after the one currently annotated. A numeric prefix argument is a repeat count.

j

Annotate the revision indicated by the current line.

a

Annotate the revision before the one indicated by the current line. This is useful to see the state the file was in before the change on the current line was made.

f

Show in a buffer the file revision indicated by the current line.

d

Display the diff between the current line’s revision and the previous revision. This is useful to see what the current line’s revision actually changed in the file.

D

Display the diff between the current line’s revision and the previous revision for all files in the changeset (for VC systems that support changesets). This is useful to see what the current line’s revision actually changed in the tree.

l

Show the log of the current line’s revision. This is useful to see the author’s description of the changes in the revision on the current line.

w

Annotate the working revision–the one you are editing. If you used p and n to browse to other revisions, use this key to return to your working revision.

v

Toggle the annotation visibility. This is useful for looking just at the file contents without distraction from the annotations.